JavaScript Temporal API: Manipulasi Tanggal dan Waktu Modern

Objek Date JavaScript telah lama menjadi sumber frustrasi bagi pengembang. Kemampuannya yang dapat diubah, kurangnya dukungan zona waktu bawaan, dan API yang canggung telah menyebabkan banyak sekali pustaka dan solusi. Untungnya, Temporal API bertujuan untuk mengatasi kekurangan ini, menyediakan solusi modern, intuitif, dan sadar zona waktu untuk manipulasi tanggal dan waktu dalam JavaScript.

Apa itu Temporal API?

Temporal API adalah objek global baru, Temporal, yang menyediakan cara modern dan terstandarisasi untuk bekerja dengan tanggal dan waktu di JavaScript. Dirancang untuk menggantikan objek Date warisan, menawarkan peningkatan signifikan dalam hal desain API, ketidakberubahan, dukungan zona waktu, dan kegunaan secara keseluruhan. Ini adalah bagian dari proposal ECMAScript dan sedang diimplementasikan di mesin JavaScript utama.

Manfaat utama dari Temporal API:

• Ketidakberubahan: Objek Temporal tidak dapat diubah, yang berarti bahwa operasi pada objek tersebut mengembalikan objek baru, bukan memodifikasi objek aslinya. Ini membantu mencegah efek samping yang tidak terduga dan membuat kode lebih mudah dipahami.
• API yang Jelas: API dirancang agar lebih intuitif dan konsisten daripada objek Date warisan.
• Dukungan Zona Waktu: Temporal menyediakan dukungan yang kuat untuk zona waktu, memungkinkan Anda bekerja dengan tanggal dan waktu di berbagai lokasi di seluruh dunia.
• Dukungan Kalender: Selain kalender Gregorian, API memungkinkan penggunaan sistem kalender lain, memfasilitasi aplikasi global.
• Penanganan Detik Kabisat: Temporal API memperhitungkan detik kabisat, menyediakan perhitungan waktu yang lebih akurat.

Memulai dengan Temporal

Meskipun Temporal API masih dalam pengembangan dan belum didukung sepenuhnya di semua browser dan lingkungan Node.js, Anda dapat menggunakan polyfill untuk mulai bereksperimen dengannya hari ini. Anda dapat menginstal polyfill melalui npm:

            npm install @js-temporal/polyfill
            

              
                Copy
              
            
          

Kemudian, impor polyfill dalam kode JavaScript Anda:

            import { Temporal } from '@js-temporal/polyfill';
            

              
                Copy
              
            
          

Setelah polyfill diinstal, Anda dapat mulai menggunakan objek Temporal dan berbagai kelasnya.

Kelas Temporal Inti

Temporal API menyediakan beberapa kelas utama untuk bekerja dengan tanggal dan waktu:

• Temporal.PlainDate: Mewakili tanggal kalender (tahun, bulan, dan hari) tanpa informasi zona waktu atau waktu siang hari.
• Temporal.PlainTime: Mewakili waktu siang hari (jam, menit, detik, dan pecahan detik) tanpa informasi tanggal atau zona waktu apa pun.
• Temporal.PlainDateTime: Mewakili tanggal dan waktu tanpa informasi zona waktu apa pun.
• Temporal.ZonedDateTime: Mewakili tanggal dan waktu dengan zona waktu tertentu.
• Temporal.Instant: Mewakili titik waktu tertentu, diukur dalam nanodetik sejak zaman Unix (1 Januari 1970, pukul 00:00:00 Waktu Universal Terkoordinasi (UTC)).
• Temporal.TimeZone: Mewakili zona waktu.
• Temporal.Duration: Mewakili durasi waktu, seperti jam, menit, atau detik.
• Temporal.Now: Menyediakan akses ke tanggal dan waktu saat ini.

Bekerja dengan PlainDate

Kelas Temporal.PlainDate mewakili tanggal tanpa informasi zona waktu atau waktu siang hari. Berguna untuk merepresentasikan ulang tahun, hari jadi, atau acara berbasis tanggal lainnya.

Membuat PlainDate:

            const plainDate = Temporal.PlainDate.from({ year: 2024, month: 10, day: 26 });
console.log(plainDate.toString()); // Output: 2024-10-26
            

              
                Copy
              
            
          

Anda juga dapat membuat PlainDate dari string dalam format ISO 8601:

            const plainDateFromString = Temporal.PlainDate.from('2024-12-25');
console.log(plainDateFromString.toString()); // Output: 2024-12-25
            

              
                Copy
              
            
          

Mengakses Komponen Tanggal:

            const year = plainDate.year; // 2024
const month = plainDate.month; // 10
const day = plainDate.day;   // 26
const dayOfWeek = plainDate.dayOfWeek; // Hari dalam seminggu (1-7, Senin-Minggu)
const dayOfYear = plainDate.dayOfYear; // Hari dalam setahun (1-366)
const daysInMonth = plainDate.daysInMonth; // Jumlah hari dalam sebulan
const isLeapYear = plainDate.isLeapYear;   // Boolean yang menunjukkan apakah tahun tersebut adalah tahun kabisat
            

              
                Copy
              
            
          

Menambahkan dan Mengurangi Hari:

            const nextDay = plainDate.add({ days: 1 });
console.log(nextDay.toString()); // Output: 2024-10-27

const previousWeek = plainDate.subtract({ weeks: 1 });
console.log(previousWeek.toString()); // Output: 2024-10-19
            

              
                Copy
              
            
          

Membandingkan Tanggal:

            const anotherDate = Temporal.PlainDate.from({ year: 2024, month: 11, day: 15 });

if (plainDate.equals(anotherDate)) {
  console.log('Tanggal sama');
} else if (plainDate.lessThan(anotherDate)) {
  console.log('plainDate lebih awal dari anotherDate');
} else {
  console.log('plainDate lebih lambat dari anotherDate');
}
// Output: plainDate lebih awal dari anotherDate
            

              
                Copy
              
            
          

Bekerja dengan PlainTime

Kelas Temporal.PlainTime mewakili waktu siang hari tanpa informasi tanggal atau zona waktu apa pun. Berguna untuk merepresentasikan jam buka, waktu pertemuan, atau acara berbasis waktu lainnya.

Membuat PlainTime:

            const plainTime = Temporal.PlainTime.from({ hour: 14, minute: 30, second: 0 });
console.log(plainTime.toString()); // Output: 14:30:00
            

              
                Copy
              
            
          

Anda juga dapat membuat PlainTime dari string dalam format ISO 8601:

            const plainTimeFromString = Temporal.PlainTime.from('09:00:00');
console.log(plainTimeFromString.toString()); // Output: 09:00:00
            

              
                Copy
              
            
          

Mengakses Komponen Waktu:

            const hour = plainTime.hour;   // 14
const minute = plainTime.minute; // 30
const second = plainTime.second; // 0
const millisecond = plainTime.millisecond; // 0
const microsecond = plainTime.microsecond; // 0
const nanosecond = plainTime.nanosecond;   // 0
            

              
                Copy
              
            
          

Menambahkan dan Mengurangi Waktu:

            const laterTime = plainTime.add({ minutes: 15 });
console.log(laterTime.toString()); // Output: 14:45:00

const earlierTime = plainTime.subtract({ hours: 1 });
console.log(earlierTime.toString()); // Output: 13:30:00
            

              
                Copy
              
            
          

Membandingkan Waktu:

            const anotherTime = Temporal.PlainTime.from({ hour: 15, minute: 0, second: 0 });

if (plainTime.equals(anotherTime)) {
  console.log('Waktu sama');
} else if (plainTime.lessThan(anotherTime)) {
  console.log('plainTime lebih awal dari anotherTime');
} else {
  console.log('plainTime lebih lambat dari anotherTime');
}
// Output: plainTime lebih awal dari anotherTime
            

              
                Copy
              
            
          

Bekerja dengan PlainDateTime

Kelas Temporal.PlainDateTime mewakili tanggal dan waktu tanpa informasi zona waktu apa pun. Ini menggabungkan fungsionalitas PlainDate dan PlainTime.

Membuat PlainDateTime:

            const plainDateTime = Temporal.PlainDateTime.from({ year: 2024, month: 10, day: 26, hour: 14, minute: 30, second: 0 });
console.log(plainDateTime.toString()); // Output: 2024-10-26T14:30:00
            

              
                Copy
              
            
          

Anda juga dapat membuat PlainDateTime dari string dalam format ISO 8601:

            const plainDateTimeFromString = Temporal.PlainDateTime.from('2024-12-25T09:00:00');
console.log(plainDateTimeFromString.toString()); // Output: 2024-12-25T09:00:00
            

              
                Copy
              
            
          

Mengakses Komponen Tanggal dan Waktu:

            const year = plainDateTime.year;   // 2024
const month = plainDateTime.month; // 10
const day = plainDateTime.day;     // 26
const hour = plainDateTime.hour;   // 14
const minute = plainDateTime.minute; // 30
const second = plainDateTime.second; // 0
            

              
                Copy
              
            
          

Menambahkan dan Mengurangi Tanggal dan Waktu:

            const nextDayAndTime = plainDateTime.add({ days: 1, hours: 2 });
console.log(nextDayAndTime.toString()); // Output: 2024-10-27T16:30:00

const previousWeekAndTime = plainDateTime.subtract({ weeks: 1, minutes: 30 });
console.log(previousWeekAndTime.toString()); // Output: 2024-10-19T14:00:00
            

              
                Copy
              
            
          

Mengonversi ke PlainDate dan PlainTime:

            const plainDateFromDateTime = plainDateTime.toPlainDate();
console.log(plainDateFromDateTime.toString()); // Output: 2024-10-26

const plainTimeFromDateTime = plainDateTime.toPlainTime();
console.log(plainTimeFromDateTime.toString()); // Output: 14:30:00
            

              
                Copy
              
            
          

Bekerja dengan ZonedDateTime

Kelas Temporal.ZonedDateTime mewakili tanggal dan waktu dengan zona waktu tertentu. Ini sangat penting untuk aplikasi yang perlu menangani tanggal dan waktu di berbagai lokasi di seluruh dunia. Tidak seperti objek Date warisan, Temporal menyediakan dukungan zona waktu bawaan.

Membuat ZonedDateTime:

            const zonedDateTime = Temporal.ZonedDateTime.from({ year: 2024, month: 10, day: 26, hour: 14, minute: 30, second: 0, timeZone: 'America/Los_Angeles' });
console.log(zonedDateTime.toString()); // Output: 2024-10-26T14:30:00-07:00[America/Los_Angeles]
            

              
                Copy
              
            
          

Anda juga dapat membuat ZonedDateTime dari Instant dan zona waktu:

            const instant = Temporal.Instant.fromEpochSeconds(1666785000); // Contoh stempel waktu
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO('Europe/London');
console.log(zonedDateTimeFromInstant.toString()); // Output akan bervariasi berdasarkan instant yang sebenarnya, tetapi akan mencerminkan tanggal/waktu di Eropa/London
            

              
                Copy
              
            
          

Mengakses Komponen Tanggal dan Waktu:

            const year = zonedDateTime.year;   // 2024
const month = zonedDateTime.month; // 10
const day = zonedDateTime.day;     // 26
const hour = zonedDateTime.hour;   // 14
const minute = zonedDateTime.minute; // 30
const second = zonedDateTime.second; // 0
const timeZone = zonedDateTime.timeZone; // Objek Temporal.TimeZone
            

              
                Copy
              
            
          

Mengonversi Antara Zona Waktu:

            const newYorkDateTime = zonedDateTime.withTimeZone('America/New_York');
console.log(newYorkDateTime.toString()); // Output: 2024-10-26T17:30:00-04:00[America/New_York]
            

              
                Copy
              
            
          

Menangani Waktu Musim Panas (DST):

Temporal secara otomatis menangani transisi DST. Saat menambahkan atau mengurangi waktu, ia memperhitungkan DST, memastikan hasil yang akurat. Misalnya, pertimbangkan pertemuan yang dijadwalkan melintasi transisi DST di Jerman:

            const meetingStart = Temporal.ZonedDateTime.from({ year: 2024, month: 3, day: 31, hour: 2, minute: 30, timeZone: 'Europe/Berlin' });
const meetingEnd = meetingStart.add({ hours: 1 }); // Menambahkan 1 jam
console.log(meetingEnd.toString()); // Output: 2024-03-31T03:30:00+02:00[Europe/Berlin]. Perhatikan perubahan offset karena DST
            

              
                Copy
              
            
          

Bekerja dengan Instant

Kelas Temporal.Instant mewakili titik waktu tertentu, diukur dalam nanodetik sejak zaman Unix. Berguna untuk menyimpan dan membandingkan momen waktu yang tepat.

Membuat Instant:

            const instant = Temporal.Instant.fromEpochSeconds(1666785000); // Contoh stempel waktu Unix dalam detik
console.log(instant.toString()); // Output akan menjadi representasi string ISO dari instant tersebut
            

              
                Copy
              
            
          

Mengonversi ke ZonedDateTime:

            const zonedDateTimeFromInstant = instant.toZonedDateTimeISO('America/Los_Angeles');
console.log(zonedDateTimeFromInstant.toString()); // Output: Tanggal dan waktu di America/Los_Angeles yang sesuai dengan instant
            

              
                Copy
              
            
          

Membandingkan Instants:

            const anotherInstant = Temporal.Instant.fromEpochSeconds(1666790000);

if (instant.equals(anotherInstant)) {
  console.log('Instants sama');
} else if (instant.lessThan(anotherInstant)) {
  console.log('instant lebih awal dari anotherInstant');
} else {
  console.log('instant lebih lambat dari anotherInstant');
}
// Output: instant lebih awal dari anotherInstant
            

              
                Copy
              
            
          

Bekerja dengan Duration

Kelas Temporal.Duration mewakili durasi waktu, seperti jam, menit, atau detik. Berguna untuk menghitung perbedaan antara dua tanggal atau waktu.

Membuat Duration:

            const duration = Temporal.Duration.from({ hours: 2, minutes: 30 });
console.log(duration.toString()); // Output: PT2H30M
            

              
                Copy
              
            
          

Menghitung Perbedaan Antara Tanggal/Waktu:

            const startDate = Temporal.PlainDateTime.from({ year: 2024, month: 1, day: 1, hour: 0, minute: 0, second: 0 });
const endDate = Temporal.PlainDateTime.from({ year: 2024, month: 1, day: 3, hour: 12, minute: 30, second: 0 });
const difference = endDate.since(startDate);
console.log(difference.toString()); // Output: P2DT12H30M

// Mengakses komponen durasi
console.log(difference.days);    // 2
console.log(difference.hours);   // 12
console.log(difference.minutes); // 30
            

              
                Copy
              
            
          

Menambahkan Durasi ke Tanggal/Waktu:

            const newDate = startDate.add(duration);
console.log(newDate.toString()); // Output: 2024-01-03T02:30:00
            

              
                Copy
              
            
          

Bekerja dengan Kalender

Temporal API mendukung sistem kalender yang berbeda selain kalender Gregorian. Meskipun belum sepenuhnya diterapkan di semua polyfill dan mesin, tujuannya adalah untuk memungkinkan aplikasi menangani tanggal dalam kalender khusus untuk berbagai budaya. Misalnya, untuk menggunakan kalender Jepang (secara hipotetis, karena implementasinya masih berkembang):

            // Ini adalah contoh konseptual karena dukungan kalender masih dalam pengembangan
// const japaneseDate = Temporal.PlainDate.from({ year: 2024, month: 10, day: 26, calendar: 'japanese' });
// console.log(japaneseDate.toString()); // Diharapkan: Output diformat sesuai dengan kalender Jepang

            

              
                Copy
              
            
          

Catatan: Dukungan kalender adalah fitur yang berkembang dari Temporal API, dan fungsionalitas penuh belum tersedia secara universal.

Contoh Praktis dan Kasus Penggunaan

Temporal API menawarkan berbagai kemungkinan untuk menangani tanggal dan waktu dalam JavaScript. Berikut adalah beberapa contoh praktis dan kasus penggunaan:

• Penjadwalan Janji Temu: Buat aplikasi penjadwalan yang memungkinkan pengguna memesan janji temu di zona waktu lokal mereka. Temporal.ZonedDateTime memudahkan konversi antar zona waktu dan menangani transisi DST. Untuk klinik di Berlin yang menjadwalkan janji temu secara global:

            const appointmentTimeBerlin = Temporal.ZonedDateTime.from({ year: 2024, month: 11, day: 5, hour: 10, minute: 0, timeZone: 'Europe/Berlin' });
const appointmentTimeLA = appointmentTimeBerlin.withTimeZone('America/Los_Angeles');
console.log(`Waktu Janji Temu di Berlin: ${appointmentTimeBerlin.toString()}`);
console.log(`Waktu Janji Temu di Los Angeles: ${appointmentTimeLA.toString()}`);
            

              
                Copy
              
            
          

• Menghitung Usia: Tentukan usia pengguna berdasarkan tanggal lahir mereka. PlainDate memungkinkan Anda merepresentasikan tanggal lahir tanpa informasi zona waktu apa pun.

            const birthDate = Temporal.PlainDate.from({ year: 1990, month: 5, day: 15 });
const today = Temporal.Now.plainDateISO();
const age = today.year - birthDate.year - (today.month < birthDate.month || (today.month === birthDate.month && today.day < birthDate.day) ? 1 : 0);
console.log(`Usia: ${age}`);
            

              
                Copy
              
            
          

• Menampilkan Tanggal dan Waktu dalam Format Berbeda: Format tanggal dan waktu sesuai dengan lokal pengguna. Meskipun fitur internasionalisasi (Intl) terpisah, objek Temporal dapat dengan mudah diformat menggunakan toLocaleString() atau metode serupa saat dikombinasikan dengan fitur API Intl.

            const zonedDateTimeNow = Temporal.Now.zonedDateTimeISO('en-GB');
console.log(zonedDateTimeNow.toLocaleString('en-GB'));
console.log(zonedDateTimeNow.toLocaleString('de-DE'));
            

              
                Copy
              
            
          

• Melacak Durasi Acara: Hitung durasi acara dan tampilkan dalam format yang mudah dibaca manusia. Duration memungkinkan Anda merepresentasikan perbedaan waktu antara dua tanggal atau waktu.

            const eventStart = Temporal.Instant.fromEpochSeconds(1700000000); // Contoh stempel waktu mulai
const eventEnd = Temporal.Instant.fromEpochSeconds(1700005000);   // Contoh stempel waktu akhir
const durationOfEvent = eventEnd.since(eventStart);
console.log(`Durasi acara: ${durationOfEvent.minutes} menit`);
            

              
                Copy
              
            
          

Praktik Terbaik untuk Menggunakan Temporal API

Berikut adalah beberapa praktik terbaik yang perlu diingat saat menggunakan Temporal API:

• Gunakan Ketidakberubahan: Rangkul ketidakberubahan objek Temporal. Hindari memodifikasi objek secara langsung. Sebagai gantinya, buat objek baru menggunakan metode seperti add, subtract, dan with.
• Tangani Zona Waktu dengan Hati-hati: Perhatikan zona waktu saat bekerja dengan tanggal dan waktu. Gunakan ZonedDateTime saat Anda perlu merepresentasikan tanggal dan waktu di zona waktu tertentu.
• Gunakan Nama Variabel yang Jelas: Gunakan nama variabel deskriptif yang dengan jelas menunjukkan jenis objek Temporal yang digunakan (misalnya, plainDate, zonedDateTime, duration).
• Pertimbangkan Polyfill: Karena Temporal masih relatif baru, pastikan dukungan yang cukup dengan menggunakan pustaka polyfill jika diperlukan.
• Validasi Input: Selalu validasi input pengguna untuk memastikan bahwa tanggal dan waktu dalam format yang benar.

Migrasi dari Tanggal Warisan

Migrasi dari objek Date warisan dapat menjadi proses bertahap. Pertimbangkan strategi ini:

• Adopsi Inkremen: Mulai gunakan Temporal dalam kode baru sambil mempertahankan Date di bagian aplikasi Anda yang ada.
• Fungsi Pembungkus: Buat fungsi pembungkus yang mengonversi antara objek Date dan Temporal untuk memfasilitasi interoperabilitas selama migrasi.
• Pengujian yang Menyeluruh: Uji migrasi secara ekstensif untuk memastikan bahwa semua perhitungan tanggal dan waktu akurat.

Temporal API vs. Moment.js

Moment.js adalah pustaka populer untuk manipulasi tanggal dan waktu di JavaScript, tetapi sekarang dianggap sebagai proyek warisan dan dalam mode pemeliharaan. Temporal API menyediakan solusi yang lebih modern dan terstandarisasi yang mengatasi banyak kekurangan Moment.js. Moment.js dapat diubah dan kurang dukungan zona waktu asli. Temporal API tidak dapat diubah dan memiliki dukungan zona waktu asli.

Kesimpulan

JavaScript Temporal API mewakili peningkatan signifikan dibandingkan objek Date warisan. Ketidakberubahannya, API yang jelas, dukungan zona waktu, dan dukungan kalender menjadikannya alat yang ampuh untuk menangani tanggal dan waktu dalam aplikasi JavaScript modern. Meskipun adopsi masih berkembang, menggunakan polyfill memungkinkan Anda untuk mulai memanfaatkan manfaatnya hari ini. Seiring dengan dukungan API yang lebih luas, diharapkan menjadi cara standar untuk bekerja dengan tanggal dan waktu di JavaScript.

Rangkul Temporal API dan buka cara yang lebih efisien dan andal untuk mengelola tanggal dan waktu dalam proyek Anda, memastikan aplikasi Anda menangani zona waktu dan perhitungan global secara akurat.